package de.preamp.clients.java.net;

import java.io.IOException;
import java.util.Collection;

import org.json.JSONException;

import de.preamp.clients.java.data.Artist;
import de.preamp.clients.java.data.Track;
import de.preamp.clients.java.utils.UpdateStatus;

/**
 * Defines the operations needed by the program for using the preamp Server. For
 * an abstract definition see {@link http
 * ://code.google.com/p/preamp/wiki/ServerApiAbstract}
 * 
 * @author André Stannek
 * @version 2010-03-21
 */
public interface ServerConnection
{
    /**
     * Gets a {@link de.preamp.clients.java.data.Track} object from the
     * preamp-server using the unique ID (primary key) for the lookup in the
     * database.
     * 
     * @param identifier
     *            unique identifier of a
     *            {@link de.preamp.clients.java.data.Track}
     * @return the matching {@link de.preamp.clients.java.data.Track}
     * @throws IOException
     *             if server returned a broken result
     * @throws JSONException
     *             if server conenction was impossible
     */
    Track getMediaFile(String identifier) throws IOException, JSONException;

    /**
     * Sets the rating of a media file in the database identified by its unique
     * ID (primary key). The rating maintains the id3v2.4 Popularimeter (POPM)
     * Field. 0 = undefined, 1 = low, 255 = high. For now this client side
     * implementation ignores the e-mail address and playcount witch are part of
     * the POPM field
     * 
     * @param identifier
     *            unique identifier of a
     *            {@link de.preamp.clients.java.data.Track}
     * @param rating
     *            the rating for the media file, 0 for undefined, 1 is lowest,
     *            255 is highest
     */
    void setRating(String identifier, short rating);

    /**
     * requests the complete media collection from the server.
     * 
     * @return a {@link Collection} of all media files in the library
     * @throws IOException
     *             if server returned a broken result
     * @throws JSONException
     *             if server connection was impossible
     */
    Collection<Track> getLibrary() throws IOException, JSONException;

    /**
     * Looks up files in the media library, matching a search keyword. The
     * result contains all media files matching the keyword in ANY id3v2.4 tag
     * field.
     * 
     * @param keyword
     *            a word the result will be filtered by
     * @return a {@link Collection} of all
     *         {@link de.preamp.clients.java.data.Track}s matching the search
     *         keyword
     * @throws IOException
     *             if server returned a broken result
     * @throws JSONException
     *             if server connection was impossible
     */
    Collection<Track> getFiles(String keyword) throws IOException,
	    JSONException;

    /**
     * Looks up files in the media library, matching a search keyword. The
     * result contains all media files matching the keyword in the id3v2.4
     * artist tag field (TPE1).
     * 
     * @param artist
     *            a artist name the result will be filtered by
     * @return a {@link Collection} of all
     *         {@link de.preamp.clients.java.data.Track}s where the artist tag
     *         field matches the artist keyword
     * @throws IOException
     *             if server returned a broken result
     * @throws JSONException
     *             if server connection was impossible
     */
    Collection<Track> getFilesByArtist(String artist) throws IOException,
	    JSONException;

    /**
     * Gets the artists from the media library on the server.
     * 
     * @return a collection of all artists available in the media library
     * @throws IOException
     *             if server returned a broken result
     * @throws JSONException
     *             if server connection was impossible
     */
    Collection<Artist> getAllArtists() throws JSONException, IOException;

    /**
     * Causes the preamp server to begin updating it's library.
     * 
     * @return true if the update is successfully started, false otherwise
     * @throws IOException
     *             if server returned a broken result
     * @throws JSONException
     *             if server connection was impossible
     */
    boolean startUpdate() throws IOException, JSONException;

    /**
     * Creates an {@link UpdateStatus} object with present information about the
     * update from the server.
     * 
     * @return the status of the update
     * @throws IOException
     *             if server returned a broken result
     * @throws JSONException
     *             if server connection was impossible
     */
    UpdateStatus updateStatus() throws IOException, JSONException;

}
